SHORTCUTS CORNER

Get help and suggestions for your iOS shortcuts and productivity apps.

Shortcuts Essentials

Automating Ulysses 2.8

• Federico

Last week, the developers at Ulysses released version 2.8 of the popular text editor, which, among various improvements, brought a unification of the x-callback-URL API across the Mac and iOS. As a heavy user of the app (I’ve been writing almost everything in Ulysses for a year now), I immediately got to work and started playing around with the new automation features in the app.

With version 2.8, Ulysses automation is now effectively split in two approaches: there are some visual actions in Workflow that don’t require any understanding of URL schemes, and there are new commands that require implementing URL schemes by hand if you want to call them via Workflow. Obviously, you can mix and match built-in Ulysses visual actions with the new URL schemes for an even more powerful automation setup in Workflow.

Upon reading the updated docs on the Ulysses website, I came across a notable caveat. Some URL schemes in Ulysses 2.8 require users to pass an authentication token embedded in the URL scheme. Here’s how the developers describe it:

To protect the Ulysses library against access from malicious apps, actions that expose content or destructively change require the calling app to be authorized.

This token is generated on a per-app and per-device basis: if you’re the developer of an app that wants to integrate with Ulysses, each version of the app on multiple devices will have to store a token to authorize with Ulysses 2.8. When using built-in Ulysses actions, Workflow takes care of fetching the token from Ulysses the first time it’s authorized by the user; the token is then stored “invisibly” in the app, and automatically passed along with action parameters when executing a specific Ulysses action. But if you want to call the new Ulysses 2.8 URL schemes from Workflow manually, you’re on your own: there’s no way to access the token Ulysses has already granted to Workflow, and you’ll have to pass one manually.

Therefore, before considering dedicated workflows for the new APIs in version 2.8, I had to come up with a system to handle authorization easily and seamlessly for users. As you might imagine at this point, my solution – which I’ve been testing for the past week – involves running an Authorize Ulysses workflow as a function and storing a permanent token in a text file in iCloud Drive.

Authorize Ulysses

The workflow’s underlying concept is deceptively simple. The workflow checks for a text file with a specific file name in the /Workflow/ folder in iCloud Drive. If the file exists, the workflow reads the contents of the file – the token to include in the URL scheme. If the file doesn’t exist, Workflow authenticates with Ulysses, receives a token, and saves it as a file in iCloud Drive. By running this task as a function – a workflow called by another workflow – the app can check at runtime if a token is available, which suggests Workflow has already been authenticated by Ulysses. Any workflow that implements this function will work regardless of the current authentication status; it’ll work if there is an existing token, and it’ll work if there’s no token, too.

Under the hood, the workflow starts by checking for a text file in iCloud Drive. Because tokens are issued on each instance of the calling app, I used the ‘Get Device Details’ action to get the name of the device where Workflow is currently running. The device name is used to create separate tokens for Workflow on the iPhone and Workflow on the iPad, which should prevent issues with attempting to use the same token on multiple devices. With this system, each version of Workflow on each device gets its own token.

To check if the text file with the token exists, the workflow attempts to get the file from iCloud Drive. With a ‘Count’ action, we count the number of files: if it’s 0, the text file doesn’t exist; if it’s 1, Workflow has found the text file in iCloud Drive. If the file exists, there’s nothing else the workflow needs to do besides reading the contents of the file and setting the token as final text output.

If there’s no text file, though, Workflow needs to authorize with Ulysses, get a token, and save it. To do this, we can call the ulysses://x-callback-url/authorize endpoint, passing along the name of our “custom app” (WorkflowMS) to receive a token. Instead of using the regular ‘Open URLs’ action, we need to use ‘Open X-Callback URL’ and put a ‘Wait to Return’ action after it. This way, Workflow will launch Ulysses and pause the workflow; Ulysses will then issue a token and relaunch Workflow, which will restart the workflow after the ‘Wait to Return’ action and, finally, save the token into the text file.

Note how, thanks to Magic Variables, we can easily fetch the output of the callback URL as ‘X-Callback Result’. In URL scheme lingo, this is the x-success parameter, which has been decoded by Workflow and extracted as text.

From now on, every time you want to automate Ulysses URL schemes that have no visual action counterpart in Workflow, I suggest installing this workflow to handle URL scheme authorization. Running this workflow inside other workflows as a function is easier than having to manually copy and paste a token every time, and it also makes it possible to share Ulysses workflows with other users while giving them an option to quickly generate and use their own tokens.

You can get the workflow here.

Export Multiple Ulysses Sheets at Once

Now for the fun stuff.

Among Ulysses’ new automation features, there’s an action to return information for all the sheets contained in a group. This action isn’t exposed natively in Workflow, and it needs to be put together manually with URL scheme authorization. I was intrigued by this action because it enables batch operations on multiple sheets at once through Workflow – something I’ve been thinking about in preparation for this year’s iOS 11 review.

To demonstrate the new x-callback-URL API in Ulysses 2.8 and showcase its integration with Workflow, I’ve created a workflow to fetch multiple sheets from a Ulysses group and export them to Dropbox. The Dropbox part is mostly a proof of concept: you can replace this action with whatever you prefer. I only wanted to provide a foundation for a system that can chain Ulysses and Workflow and perform actions on multiple sheets.

The workflow starts by running Authorize Ulysses as an external module; the token passed by the workflow is saved as a Magic Variable we can use in other actions. Then, we have the only ‘Text’ action you’ll have to configure yourself: the callback ID of the Ulysses group we want to automate. To fetch this identifier, you can open Ulysses, find a group, swipe left on it, and select More -> Share -> Copy Callback Identifier. This is a unique ID that can be used to reference a group of sheets from outside Ulysses.

With the authorization token and group ID set, the workflow can now launch Ulysses with the ‘Open X-Callback URL’ action and read the information for a group passed by the app. Here’s my recommendation: because there’s going to be a lot of back and forth between Ulysses and Workflow using callbacks, in my experience it’s best to run this workflow in full-screen mode rather than Split View. I know that it’s not pretty to look at full-screen apps launching each other in rapid succession, but the animation in iOS 10 is better than in the old days of URL schemes, and I haven’t run into any bugs.

The first time Ulysses launches, it’ll see the ID and token passed by Workflow, and it will relaunch Workflow with text included in the x-success parameter. This text is a dictionary that represents the group in Ulysses, and the dictionary is not pretty.

Obviously, I wanted to present a nicer-looking list of sheets in the workflow. To do that, I iterated over every item in the sheets dictionary and assembled a new dictionary from scratch using the title of a sheet as key, and its ID as value. After some necessary reformatting to coerce Text into Dictionary, here’s what the list of sheets contained in a group looks like:

At this point, we have a dictionary of sheets that, when presented as a list with the ‘Choose from List’ action, will output the ID of each sheet. To read the full-text contents of each sheet, we have to use a Repeat loop. For each sheet ID, Workflow will launch Ulysses with the native ‘Get Ulysses Sheet’ action and automatically return with an object that contains Magic Variables for the Ulysses sheet. Notice how we’re combining URL scheme actions with native Ulysses ones in Workflow, and how the ‘Get Ulysses Sheet’ action doesn’t need to be combined with ‘Get Details of Ulysses Sheet’ anymore because of Magic Variables. There’s some great flexibility at play here.

This is where the “proof of concept” part of the workflow starts. When Ulysses re-launches Workflow to pass a sheet object, there are several Magic Variables to choose from:

• Contents (sheet text)
• Title
• Identifier
• Keywords
• Notes
• Name

If you want, you can extract each of these values for each sheet you’ve picked from the list. In my workflow, I went with a simple approach: each sheet is converted to a .txt file that is saved to a predefined Dropbox folder. This way, even if you use iCloud in Ulysses (like I do), you can quickly export multiple sheets as Markdown to Dropbox without having to compile them to a single text file or, worse, having to interact with a Dropbox interface for every sheet.

In practice, though, you can use this workflow as a framework to build anything you need for multi-sheet operations with Ulysses and Workflow. Maybe you want to find a string of text in each sheet and, if there’s a match, send that sheet somewhere else. Maybe you want to compress multiple sheets and share them as a .zip archive. As long as you follow the basic rules of actions inside a Repeat block, you’re free to customize this workflow for whatever suits you best.

I’m considering some of the other actions available in Ulysses 2.8, but I haven’t figured out how to implement them yet. For instance, it’s now possible to retrieve and update notes contained in a sheet, which could be interesting to keep an up-to-date set of comments for specific sheets. I have come up with a MacStories-specific workflow to archive and recreate sheets in a specific group, but it’s mostly based on the workflow I described above.

In general, I feel like Ulysses has turned into one of the premier examples of x-callback-url automation on iOS, and I hope others will follow their approach – that is, until Apple finally provides a better, safer, more powerful solution for everyone.

You can get the workflow here.

Submit a Shortcut Request

SHORTCUTS CORNER

Get help and suggestions for your iOS shortcuts and productivity apps.

Member Requests

• Federico

There is no native way to monitor a Spotify playlist in the background on iOS and add new songs to Apple Music. However, because Spotify has an open web API, we can use Zapier to monitor a specific playlist and pass details for songs added to it using Pushover, which will trigger Workflow on iOS.

Here’s my idea: on Zapier, we can set up a trigger for ‘New Track Added to Playlist’. This trigger fires every time any song is added to a specific playlist from your account.

The song object contains a lot of metadata; most of those elements are meant to identify an item from the Spotify API, but we can extract attributes such as the song’s name, artist, and album and use them to construct a string of text we’ll pass to Workflow on iOS.

To send information from Zapier (cloud) to iOS (device), we can use Pushover as the middleman. Pushover is a notification service that can be hooked up to Zapier to send custom notifications to your iOS devices. These notifications can include a URL that will be automatically launched upon tapping the notification. As you can imagine, instead of attaching a traditional web URL to the notification, we’ll include the Workflow URL scheme with a command to run a workflow with some input text. The text will include the details of the song added to a Spotify playlist and caught by Zapier.

To include text in a URL, though, we need to encode it. And to do so, we have to add a Code (Python) step between the Zapier trigger and the Pushover action. This simple code will fetch song attributes, join them with a custom %%ITEM%% separator, and URL-encode them.

(You can copy the Python code from this gist.)

In the Pushover action, we can set up a custom message that describes the song that was added to a trigger, and we can paste the workflow:// URL to trigger a workflow on our iOS devices. As you can see, we’re using the Quoted Text variable (the output of the Code action) to embed encoded text in the URL scheme.

When a song is added to a Spotify playlist you’re monitoring, the zap will be triggered and you’ll get a Pushover notification. Upon tapping the alert, Workflow will open to run a workflow named ZapSpotify.

The workflow takes the input text, decodes it automatically, and then splits it at the custom separator we used – %%TEXT%%. This way, we have three items we can use to search for the same song on the iTunes Store: the song’s name, artist, and album. Before searching the iTunes Store, you’ll get an alert that confirms the song’s information and asks you to continue.

The ‘Search iTunes Store’ action will then search the iTunes Music Store for the song and artist passed by Zapier through Pushover. To make sure you’re dealing with the right song (and, say, not a cover or remix), I added a ‘Choose from List’ action, which will prompt you to manually pick an item. In theory, the most accurate result should always be first in the list. Finally, the song will be added to an Apple Music playlist of your choice.

This isn’t the most elegant solution to bridge the gap between Spotify and Apple Music, but it works. In my experience, Zapier can monitor Spotify playlists for new songs without issues, and I’ve been using Pushover for a couple of years with great results. The process can’t be entirely automated – you’ll at least have to tap the notification to run the workflow – but this is as good as it gets.

You can get the workflow here.

• Federico

I struggled to put this together until I realized that there is an easy way to compare multiple files and check if the same one is repeated multiple times: we need to convert images to a text string.

The solution to this problem is encoding each image to a base64 string and using a Repeat loop to check if a variable already contains the same text string. Here’s the core of my modification to your workflow:

A loop begins for every album artwork fetched by Workflow. On each pass, the input image is encoded and a conditional block checks if a variable already contains it. On the first pass of the loop, this variable will be empty; on subsequent iterations, the variable – which is an array of items thanks to the ‘Add to Variable’ action – gets filled with unique base64 strings. This is possible thanks to the fact that the same image file always generates the same string when encoded, thus allowing us to check if the same image already exist in an array just by asking Workflow if the array contains a specific string of text.

At the end of the loop, we need to get the array and re-iterate over every item to decode it and save it in another array. This will be the variable that, when fed to ‘Combine Images,’ will generate a grid of artworks you can share.

With this system, each album artwork on the grid will be unique, and you might want to consider extending the range of items that are searched by Workflow to fetch even more artwork because all of them will be different on the final image.

You can get the modified workflow here.

• Federico

And now, an interesting workflow shared by member Brent:

Brent: Recently I wrote about how to backup and restore your Workflows. I have a variation of that workflow that I use for saving individual workflows. These might be workflows I created for others on Reddit or for my friends, but not ones I actually use myself.

The workflow starts with creating two folders in iCloud Drive stored at Workflow/Backups/Individuals. If these folders exist already, then nothing happens. The workflow will then ask you a couple questions. Do you want to backup or restore? And do you want to save/restore from all your workflows or just one?

Also, I want to thank Reddit user rawbytz who directed me to this workflow, which is the basis for the restore part of my workflow. If you want the new and improved Backup/Restore Workflow you can get it here. (Brent Clarj, @brentacPrime)

• Federico

And finally, another workflow submitted by member Toph:

Toph: I’m trying to maintain parity in my Apple Music and Spotify libraries this year and I made some additions and modifications to a Songlink workflow previously posted on MacStories Weekly.

Some benefits of this version:

• It accepts links from either Apple Music or Spotify.
• It can be run from the Today widget or the share sheet for either service. To do this, it calls another workflow, attached, called “Single URL from Input or Clipboard,” which looks for a URL in the Workflow’s input, and if none is present, looks for one in the clipboard.
• Using the Songlink API, the user can copy the link to their clipboard, open it in Safari, Apple Music, or iTunes, and can also share via any other service.
• The two most recent options I added, “Open in Spotify” and “Open in Apple Music,” fetch the Songlink page and open the enclosed URLs matching “spotify” and “itunes” respectively.

I thought you might enjoy the sheer level of nerdiness that went into this.

You can get the workflows here:

• Songlink
• Single URL from Input or Clipboard

(Toph, @toph)

Submit a Workflow Request

Submit a Shortcut Request